mercury-rails 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jeremy Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,152 @@
+= Mercury Editor
+
+Mercury Editor is a fully featured editor much like TinyMCE or CKEditor, but with a different usage paradigm.  It
+expects that an entire page is something that can be editable, and allows different types of editable regions to be
+specified.  It displays a single toolbar for every region on the page, and uses the HTML5 contentEditable features on
+block elements, instead of iframes, which allows for CSS to be applied in ways that most other editors can't handle.
+
+Mercury has been written using CoffeeScript and jQuery for the Javascript portions, and is written on top of Rails 3.1.
+
+
+== Browser Support
+
+Mercury has been written for the future, and thus doesn't support legacy browsers or browsers that don't follow the W3C
+specifications for content editing.  Any browser will be supported if they support the W3C specification in the future,
+but there aren't plans for adding support for alternate implementations at this time.
+
+Supported Browsers:
+* Chrome 10+
+* Safari 5+
+* Firefox 4+
+
+
+== The Story
+
+I was looking for a fully featured editor that didn't use iframes, and there weren't any decent ones.  My primary goal
+was to have areas that were editable, but that also allowed CSS to flow naturally.  A few have cropped up since then
+(Aloha Editor for instance), and as good as they are, none had all the features I was looking for.
+
+Mercury was written to be as simple as possible, while also providing an advanced feature set.  Instead of complex
+configuration, we chose a mix of configuration and code simplicity, which should give you a much better chance at
+customizing Mercury to suit your exact needs.  This doesn't mean there's not configuration, and what's there provides
+much of what you'll need, but efforts were taken to keep it simple and powerful.
+
+Even though it's a great editor, Mercury Editor may not be the best for your needs (based on browser support, javascript
+library, etc.) so here's a list of some other editors that you might want to check out:
+
+* {Aloha Editor}[http://www.aloha-editor.org/]
+* {jHtmlArea}[http://jhtmlarea.codeplex.com/]
+* {MarkItUp}[http://markitup.jaysalvat.com/home/]
+* {TinyMCE}[http://tinymce.moxiecode.com/]
+* {CKEditor}[http://ckeditor.com/]
+* {NicEdit}[http://nicedit.com/]
+
+
+== Project Details
+
+=== WYSIWYG Editors Suck
+
+They just do.  Which as I've learned, is primarily due to the browser implementations.  Don't get me wrong, what the
+browsers have implemented is amazing, because it's hard stuff, plain and simple.  But if you're expecting a WYSIWYG
+editor to solve all your content problems you're wrong.  A better perception is that it will solve many of them, but
+shifts some into a new area.
+
+With that being said, Mercury tries to solve many of those issues and succeeds to a great degree, but alas, it's nearly
+impossible to address everything, and the browsers don't expose enough to fix some things.  This is true for every
+editor that I've looked into as well.
+
+It's important to understand this, and the details are more suited for long nerdy blog posts, so they won't be covered
+here.
+
+=== The Code and Why
+
+==== CoffeeScript
+
+Mercury has been written entirely in CoffeeScript because it simplifies a lot of the patterns that are used, and allows
+for very readable code.  The goal was to provide good readable code that could be adjusted based on need, instead of a
+complex configuration that makes the code harder to understand and tweak.
+
+==== jQuery
+
+jQuery was used as the javascript library, but is primarily used for the selectors, traversing, and manipulating the
+DOM.  Chaining is kept to a minimum for readability, and even though much of Mercury could've been written as jQuery
+plugins, it was not.
+
+==== Rails
+
+With the asset handling that comes bundled with Rails 3.1, Rails Engines, and the gem tools, there really wasn't any
+other option.  The javascript from Mercury can be used by any back end system, and isn't limited to Rails.  Many of the
+features do require a back end, and that stuff would have to be rewritten in whatever language you wanted support for.
+The coffeescript files can be found in the repo, and I would be fully supportive of anyone who wanted to add support for
+different back end frameworks or languages.
+
+==== Specs / Integration Tests
+
+Mercury is fully tested using Jasmine (via Evergreen) and Cucumber.  You can clone the project to run the full suite.
+
+  rake spec:javascripts
+  rake cucumber
+
+
+== Features
+
+The feature list is actually pretty long, so here's a short list that need highlighting.
+
+* Previewing: Preview content while you're working to see exactly how it'll look.
+* Link Tools: Insert and edit links, including TOC/Bookmark links.
+* Media Tools: Insert and edit images, youtube videos, and vimeo videos.
+* Image Uploading: Drag images from your desktop and they'll be automatically uploaded and inserted.
+* Table Editing: Advanced table editing and creation.
+* Snippets: Insert and edit predefined and reusable bits of markup/code using drag and drop.
+* Notes: Attach notes to any page and communicate with other content authors.
+* Colaborative Editing: Edit any page that others are editing at the same time and see their changes in real time.
+
+
+== Installation
+
+Include the gem in your Gemfile
+
+  gem 'mercury-rails'
+
+Then just bundle install and you should be all set.  Browse to any existing content page and prefix it's url with /edit,
+so for instance, localhost:3000/edit/content/page to edit the content on /content/page.
+
+
+== Usage
+
+Mercury has an expectation that content regions will be on the page (not required, but probably useful).  To define
+content regions that Mercury will make editable you need to add a `mercury-region` class attribute to a div.  Then
+specify what region type by using the `data-type` attribute -- which can be *editable*, *markupable*, or *snippetable*.
+Region types are outlined below.
+
+  <div class="mercury-region" data-type="editable">
+    default content
+  </div>
+
+
+== Region Types
+
+=== Editable
+
+Editable Regions are HTML markup, and use the HTML5 contentEditable feature.  This is the core of what Mercury is about,
+and provides the most flexibility and visual representation of what the content will look like when saved.
+
+=== Markupable
+
+These regions are based on Markdown syntax (specifically the github flavored version), and isn't as full featured as the
+editable region type -- primarily because markdown is meant to be simple, so to keep it such you can't do things like
+set colors etc.  This region type is super useful if you want to keep the markup clean and simple.
+
+=== Snippetable
+
+Snippetable regions only allow snippets.  There isn't any content editing in these regions, but snippets can sometimes
+be the way to go with complex markup and functionality.  Snippets are basically chunks of reusable markup, that can be
+defined by a developer and placed into content regions later.  More on this below.
+
+
+== Snippets
+
+Snippets are reusable and configurable chunks of markup.  They can be defined by developers, and then placed anywhere in
+content regions.  When you drag a snippet into a region you'll be prompted to enter options, and after entering options
+the snippet will be rendered into the page as a preview.  Snippets can be dragged around (in snippetable regions) and
+edited or removed.

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/assets/javascripts/mercury.js

@@ -0,0 +1,30 @@
+/*!
+ * Mercury Editor is a Coffeescript and jQuery based WYSIWYG editor.  Mercury Editor utilizes the HTML5 ContentEditable
+ * spec to allow editing sections of a given page (instead of using iframes) and provides an editing experience that's as
+ * realistic as possible.  By not using iframes for editable regions it allows CSS to behave naturally.
+ *
+ * Mercury Editor was written for the future, and doesn't attempt to support legacy implementations of document editing.
+ *
+ * Currently supported browsers are
+ *   - Firefox 4+
+ *   - Chrome 10+
+ *   - Safari 5+
+ *
+ * Copyright (c) 2011 Jeremy Jackson
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ *= require_self
+ *= require mercury/mercury
+ */

data/app/assets/javascripts/mercury/dialog.js.coffee

@@ -0,0 +1,75 @@
+class @Mercury.Dialog
+
+  constructor: (@url, @name, @options = {}) ->
+    @button = @options.for
+
+    @build()
+    @bindEvents()
+    @preload()
+
+
+  build: ->
+    @element = $('<div>', {class: "mercury-dialog mercury-#{@name}-dialog loading", style: 'display:none'})
+    @element.appendTo($(@options.appendTo).get(0) ? 'body')
+
+
+  bindEvents: ->
+    @element.mousedown (event) -> event.stopPropagation()
+
+
+  preload: ->
+    @load() if @options.preload
+
+
+  toggle: (element) ->
+    if @visible then @hide() else @show()
+
+
+  resize: ->
+    @show()
+
+
+  show: ->
+    Mercury.trigger('hide:dialogs', @)
+    @visible = true
+    if @loaded
+      @element.css({width: 'auto', height: 'auto'})
+      @position(@visible)
+      @appear()
+    else
+      @position()
+      @appear()
+
+
+  position: (keepVisible) ->
+
+
+  appear: ->
+    @element.css({display: 'block', opacity: 0})
+    @element.animate {opacity: .95}, 200, 'easeInOutSine', =>
+      @load(=> @resize()) unless @loaded
+
+
+  hide: ->
+    @element.hide()
+    @visible = false
+
+
+  load: (callback) ->
+    return unless @url
+    $.ajax @url, {
+      success: (data) =>
+        @loadContent(data)
+        Mercury.dialogHandlers[@name].call(@) if Mercury.dialogHandlers[@name]
+        callback() if callback
+      error: =>
+        @hide()
+        @button.removeClass('pressed') if @button
+        alert("Mercury was unable to load #{@url} for the #{@name} dialog.")
+    }
+
+
+  loadContent: (data) ->
+    @loaded = true
+    @element.removeClass('loading')
+    @element.html(data)

data/app/assets/javascripts/mercury/dialogs/backcolor.js.coffee

@@ -0,0 +1,6 @@
+@Mercury.dialogHandlers.backcolor = ->
+  @element.find('.picker, .last-picked').click (event) =>
+    color = $(event.target).css('background-color')
+    @element.find('.last-picked').css({background: color})
+    @button.css({backgroundColor: color})
+    Mercury.trigger('action', {action: 'backcolor', value: color})

data/app/assets/javascripts/mercury/dialogs/forecolor.js.coffee

@@ -0,0 +1,6 @@
+@Mercury.dialogHandlers.forecolor = ->
+  @element.find('.picker, .last-picked').click (event) =>
+    color = $(event.target).css('background-color')
+    @element.find('.last-picked').css({background: color})
+    @button.css({backgroundColor: color})
+    Mercury.trigger('action', {action: 'forecolor', value: color})

data/app/assets/javascripts/mercury/dialogs/formatblock.js.coffee

@@ -0,0 +1,4 @@
+@Mercury.dialogHandlers.formatblock = ->
+  @element.find('[data-tag]').click (event) =>
+    tag = $(event.target).data('tag')
+    Mercury.trigger('action', {action: 'formatblock', value: tag})

data/app/assets/javascripts/mercury/dialogs/objectspanel.js.coffee

@@ -0,0 +1,10 @@
+@Mercury.dialogHandlers.objectspanel = ->
+  # make the filter work
+  @element.find('input.filter').keyup =>
+    value = @element.find('input.filter').val()
+    for snippet in @element.find('li[data-filter]')
+      if LiquidMetal.score($(snippet).data('filter'), value) == 0 then $(snippet).hide() else $(snippet).show()
+
+  # when an element is dragged, set it so we have a global object
+  @element.find('img[data-snippet]').bind 'dragstart', (event) ->
+    Mercury.snippet = $(@).data('snippet')

data/app/assets/javascripts/mercury/dialogs/style.js.coffee

@@ -0,0 +1,4 @@
+@Mercury.dialogHandlers.style = ->
+  @element.find('[data-class]').click (event) =>
+    className = $(event.target).attr('class')
+    Mercury.trigger('action', {action: 'style', value: className})

data/app/assets/javascripts/mercury/history_buffer.js.coffee

@@ -0,0 +1,30 @@
+class @Mercury.HistoryBuffer
+
+  constructor: (@maxLength = 200) ->
+    @index = 0
+    @stack = []
+    @markerRegExp = /<em class="mercury-marker"><\/em>/g
+
+
+  push: (item) ->
+    if $.type(item) == 'string'
+      return if @stack[@index] && @stack[@index].replace(@markerRegExp, '') == item.replace(@markerRegExp, '')
+    else if $.type(item) == 'object' && item.html
+      return if @stack[@index] && @stack[@index].html == item.html
+
+    @stack = @stack[0...@index + 1]
+    @stack.push(item)
+    @stack.shift() if @stack.length > @maxLength
+    @index = @stack.length - 1
+
+
+  undo: ->
+    return null if @index < 1
+    @index -= 1
+    return @stack[@index]
+
+
+  redo: ->
+    return null if @index >= @stack.length - 1
+    @index += 1
+    return @stack[@index]

data/app/assets/javascripts/mercury/mercury.js.coffee

@@ -0,0 +1,293 @@
+#
+#= require jquery-1.6
+#= require jquery-ui-1.8.13.custom.min
+#= require jquery-ui-1.8.13.sortable.custom
+#= require jquery.easing
+#= require jquery.json2
+#= require jquery.ujs
+#= require jquery.serialize_object
+#= require liquidmetal
+#
+#= require_self
+#= require ./native_extensions
+#= require ./page_editor
+#= require ./history_buffer
+#= require ./table_editor
+#= require ./dialog
+#= require ./palette
+#= require ./select
+#= require ./panel
+#= require ./modal
+#= require ./statusbar
+#= require ./toolbar
+#= require ./toolbar.button
+#= require ./toolbar.button_group
+#= require ./toolbar.expander
+#= require ./tooltip
+#= require ./snippet
+#= require ./snippet_toolbar
+#= require ./region
+#= require ./uploader
+#= require_tree ./regions
+#= require_tree ./dialogs
+#= require_tree ./modals
+#
+#= require showdown
+#
+
+@Mercury = {
+
+  version: 1.0
+
+
+  # No IE support yet because it doesn't follow the W3C standards for HTML5 contentEditable (aka designMode).
+  supported: document.getElementById && document.designMode && !$.browser.konqueror && !$.browser.msie
+
+
+  # Silent mode disables things like asking about unsaved changes before leaving the page.
+  silent: true
+
+
+  # Turning debug mode on will log events and other various things (using console.log if available).
+  debug: true
+
+
+  # Configuration
+  config: {
+
+    # Pasting (in Chrome/Safari)
+    #
+    # When copying content using webkit, it embeds all the user defined styles (from the css files) into the html style
+    # attributes directly.  When pasting this content into HTML5 contentEditable elements it leaves these intact.  This
+    # can be a desired feature, or an annoyance, so you can enable it or disable it here.  Keep in mind this will only
+    # change the behavior in webkit, as gecko doesn't do this.
+    #
+    cleanStylesOnPaste: true
+
+
+    # Image Uploading (in supported regions)
+    #
+    # If you drag images (while pressing shift) from your desktop into regions that support it, it will be uploaded to
+    # the server and inserted into the region.  This configuration allows you to specify if you want to disable/enable
+    # this feature, the accepted mime-types, file size restrictions, and other things related to uploading.
+    #
+    uploading:
+      enabled: true
+      allowedMimeTypes: ['image/jpeg', 'image/gif', 'image/png']
+      maxFileSize: 1235242880 # bytes (5 Mb by default)
+      inputName: 'image[image]'
+      url: '/images'
+
+
+    # Toolbars
+    #
+    # This is where you can customize the toolbars by adding or removing buttons, or changing them and their behaviors.
+    # Any top level object put here will create a new toolbar.  Buttons are simply nested inside the toolbars, along
+    # with button groups.
+    #
+    # Buttons can be grouped.  A button group is simply a way to wrap buttons for styling, and can also handle enabling
+    # or disabling all the buttons within it by using a context.  The table button group is a good example of this.
+    #
+    # The primary toolbar is always visible, but any other toolbar should have a name based on what type of region it's
+    # for.  The toolbar will be enabled/disabled base on what region currently has focus.  Some toolbars are custom (the
+    # snippetable toolbar for instance), and to denote that use _custom: true.  You can then build the toolbar yourself
+    # with it's own behavior.
+    #
+    # It's important to note that each of the button names (keys), in each toolbar object must be unique, regardless of
+    # if it's in a button group, or nested, etc.  This is because styling is applied to them by name.
+    #
+    # Button format: [label, description, {type: action, type: action, etc}] The available button types are:
+    #
+    # toggle:  toggles on or off when clicked, otherwise behaves like a button
+    # modal:   opens a modal window, expects the action to be one of:
+    #            a string url
+    #            a function that returns a string url
+    # panel:   opens a panel dialog, expects the action to be one of:
+    #            a string url
+    #            a function that returns a string url
+    # palette: opens a palette window, expects the action to be one of:
+    #            a string url
+    #            a function that returns a string url
+    # select:  opens a pulldown style window, expects the action to be one of:
+    #            a string url
+    #            a function that returns a string url
+    # context: calls a callback function, expects the action to be:
+    #            a function that returns a boolean to highlight the button
+    #            note: if a function isn't provided, the key will be passed to the contextHandler, in which case a
+    #                  default context will be used (for more info read the Contexts section below)
+    # mode:    toggle a given mode in the editor, expects the action to be:
+    #            a string, denoting the name of the mode
+    #            note: it's assumed that when a specific mode is turned on, all other modes will be turned off, which
+    #                  happens automatically, thus putting the editor into a specific "state"
+    # regions: allows buttons to be enabled/disabled based on what region type has focus, expects the action to be:
+    #            an array of region types (eg. ['editable', 'markupable']
+    # preload: allows some dialog views to be loaded whtn the button is created instead of on first open, expects:
+    #            a boolean
+    #            note: only used for panels, selects, and palettes
+    #
+    # Separators are any "button" that's not an array, and are expected to be a string.  You can use two different
+    # separator styles: line ('-'), and spacer (' ').
+    #
+    toolbars:
+      primary:
+        save:                  ['Save', 'Save this page']
+        preview:               ['Preview', 'Preview this page', {toggle: true, mode: true}]
+        sep1:                  ' '
+        undoredo:
+          undo:                ['Undo', 'Undo your last action']
+          redo:                ['Redo', 'Redo your last action']
+          sep:                 ' '
+        insertlink:            ['Link', 'Insert Link', {modal: '/mercury/modals/link', regions: ['editable', 'markupable']}]
+        insertmedia:           ['Media', 'Insert Media (images and videos)', {modal: '/mercury/modals/media', regions: ['editable', 'markupable']}]
+        inserttable:           ['Table', 'Insert Table', {modal: '/mercury/modals/table', regions: ['editable', 'markupable']}]
+        insertcharacter:       ['Character', 'Special Characters', {modal: '/mercury/modals/character', regions: ['editable', 'markupable']}]
+        objectspanel:          ['Snippet', 'Snippet Panel', {panel: '/mercury/panels/snippets'}]
+        sep2:                  ' '
+        historypanel:          ['History', 'Page Version History', {panel: '/mercury/panels/history'}]
+        sep3:                  ' '
+        notespanel:            ['Notes', 'Page Notes', {panel: '/mercury/panels/notes'}]
+
+      editable:
+        _regions:              ['editable', 'markupable']
+        predefined:
+          style:               ['Style', null, {select: '/mercury/selects/style', preload: true}]
+          sep1:                ' '
+          formatblock:         ['Block Format', null, {select: '/mercury/selects/formatblock', preload: true}]
+          sep2:                '-'
+        colors:
+          _regions:            ['editable']
+          backcolor:           ['Background Color', null, {palette: '/mercury/palettes/backcolor', context: true, preload: true}]
+          sep1:                ' '
+          forecolor:           ['Text Color', null, {palette: '/mercury/palettes/forecolor', context: true, preload: true}]
+          sep2:                '-'
+        decoration:
+          bold:                ['Bold', null, {context: true}]
+          italic:              ['Italicize', null, {context: true}]
+          overline:            ['Overline', null, {context: true, regions: ['editable']}]
+          strikethrough:       ['Strikethrough', null, {context: true, regions: ['editable']}]
+          underline:           ['Underline', null, {context: true, regions: ['editable']}]
+          sep:                 '-'
+        script:
+          subscript:           ['Subscript', null, {context: true}]
+          superscript:         ['Superscript', null, {context: true}]
+          sep:                 '-'
+        justify:
+          _regions:            ['editable']
+          justifyleft:         ['Align Left', null, {context: true}]
+          justifycenter:       ['Center', null, {context: true}]
+          justifyright:        ['Align Right', null, {context: true}]
+          justifyfull:         ['Justify Full', null, {context: true}]
+          sep:                 '-'
+        list:
+          insertunorderedlist: ['Unordered List', null, {context: true}]
+          insertorderedlist:   ['Numbered List', null, {context: true}]
+          sep:                 '-'
+        indent:
+          outdent:             ['Decrease Indentation', null]
+          indent:              ['Increase Indentation', null]
+          sep:                 '-'
+        table:
+          _context:            true
+          _regions:            ['editable']
+          insertrowbefore:     ['Insert Table Row', 'Insert a table row before the cursor']
+          insertrowafter:      ['Insert Table Row', 'Insert a table row after the cursor']
+          deleterow:           ['Delete Table Row', 'Delete this table row']
+          insertcolumnbefore:  ['Insert Table Column', 'Insert a table column before the cursor']
+          insertcolumnafter:   ['Insert Table Column', 'Insert a table column after the cursor']
+          deletecolumn:        ['Delete Table Column', 'Delete this table column']
+          sep1:                ' '
+          increasecolspan:     ['Increase Cell Columns', 'Increase the cells colspan']
+          decreasecolspan:     ['Decrease Cell Columns', 'Decrease the cells colspan and add a new cell']
+          increaserowspan:     ['Increase Cell Rows', 'Increase the cells rowspan']
+          decreaserowspan:     ['Decrease Cell Rows', 'Decrease the cells rowspan and add a new cell']
+          sep2:                '-'
+        rules:
+          horizontalrule:      ['Horizontal Rule', 'Insert a horizontal rule']
+          sep1:                '-'
+        formatting:
+          _regions:            ['editable']
+          removeformatting:    ['Remove Formatting', 'Remove formatting for the selection']
+          sep2:                ' '
+        editors:
+          _regions:            ['editable']
+          htmleditor:          ['Edit HTML', 'Edit the HTML content'] # example behavior below
+
+      snippetable:
+        _custom:               true
+        actions:
+          editsnippet:         ['Edit Snippet Settings', null]
+          sep1:                ' '
+          removesnippet:       ['Remove Snippet', null]
+
+
+    # Behaviors
+    #
+    # Behaviors are used to change the default behaviors of a given region type when a given button is clicked.  For
+    # example, you may prefer to add HR tags using an HR wrapped within a div with a classname (for styling).  You can
+    # add your own complex behaviors here.
+    #
+    # You can see how the behavior matches up directly with the button name.  It's also important to note that the
+    # callback functions are executed within the scope of the given region, so you have access to all it's methods.
+    # todo: figure out how this impacts different regions.. should they go away, or should they get moved into region types?
+    behaviors:
+      horizontalrule: (selection) -> selection.replace('<hr/>')
+
+      htmleditor: ->
+        Mercury.modal '/mercury/modals/htmleditor', {
+          title: 'HTML Editor',
+          fullHeight: true,
+          handler: 'htmleditor'
+        }
+
+
+    # Contexts
+    #
+    # Contexts are used callback functions used for highlighting and disabling/enabling buttons and buttongroups.  When
+    # the cursor enters an element within an html region for instance we want to disable or highlight buttons based on
+    # the properties of the given node.  You can see some examples of contexts in:
+    #
+    # Mercury.Toolbar.Button.contexts
+    # and
+    # Mercury.Toolbar.ButtonGroup.contexts
+    #
+
+
+    # Styles
+    #
+    # Mercury tries to stay as much out of your code as possible, but because regions appear within your document we
+    # need to include a few styles to indicate regions, as well as the different states of them (eg. focused).  These
+    # styles are injected into your document, and as simple as they might be, you may want to change them.  You can do
+    # so here.
+    #
+    injectedStyles: '''
+      .mercury-region, .mercury-textarea { min-height: 10px; outline: 1px dotted #09F }
+      .mercury-textarea { box-sizing: border-box; -moz-box-sizing: border-box; resize: vertical; }
+      .mercury-region:focus, .mercury-region.focus, .mercury-textarea.focus { outline: none; -webkit-box-shadow: 0 0 10px #09F, 0 0 1px #045; box-shadow: 0 0 10px #09F, 0 0 1px #045 }
+      .mercury-region:after { content: '\00a0'; display: block; visibility: hidden; clear: both; height: 0; overflow: hidden; }
+      .mercury-region table, .mercury-region td { border: 1px dotted red; }
+      '''
+  }
+
+
+  # Custom event and logging methods
+  bind: (eventName, callback) ->
+    $(document).bind("mercury:#{eventName}", callback)
+
+
+  trigger: (eventName, options) ->
+    Mercury.log(eventName, options)
+    $(document).trigger("mercury:#{eventName}", options)
+
+
+  log: ->
+    if Mercury.debug && console
+      return if arguments[0] == 'hide:toolbar'
+      try console.debug(arguments) catch e
+
+
+  # Mercury object namespaces
+  Regions: {}
+  modalHandlers: {}
+  dialogHandlers: {}
+
+}